home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODF-Interest Archive / April 96 / ODF1 Binding < prev    next >
Encoding:
Internet Message Format  |  1996-12-03  |  11.6 KB  |  [TEXT/ttxt]
  1. Subject:     ODF1 Binding
  2. Sent:        4/9/96 10:39 AM
  3. Received:    4/9/96 10:51 AM
  4. From:        Mark Lanett, mlanett@meer.net
  5. Reply-To:    ODF-Interest@CILabs.ORG
  6. To:          OpenDoc Development Framework Discussion List, ODF-Interest@CILabs.
  7.  
  8. This document concerning binding (both to OpenDoc and the Finder) is from
  9. ODF1, so some things have changed since d11. However, ODF1 is right around
  10. the corner.
  11.  
  12. Actually two documents: first, the general binding document, second, one
  13. describing the new PartInfo resource.
  14.  
  15. ---------------------------------------------------------------------
  16.  
  17. OpenDoc
  18. Development
  19. Framework
  20.  
  21.  
  22. 'nmap', Icon, & Part Signature
  23. ODF Release 1
  24.  
  25.  
  26.  
  27. Table of Contents
  28. -------------------------
  29. * Why You Need to Change Your Part's Resources
  30. * Modifying Your 'nmap' Resources
  31. * Changing Your Part Signature
  32. * Changing Your Part Icons
  33.  
  34.  
  35. Why You Need to Change Your 'nmap' Resources
  36.  
  37. Whenever you create a part editor, you must supply OpenDoc with a series of
  38. 'nmap' resources, which provide OpenDoc with a multitude of information
  39. about your part. When you create a new part using PartMaker, you get a set
  40. of 'nmap' resources, which correspond to the kinds of data supported by the
  41. part that was used to generate the PartMaker template. You need to change
  42. these resources to reflect the information contained in your part.
  43.  
  44. In addition to the 'nmap' resources, OpenDoc on the Mac OS requires you to
  45. specify a unique OSType that corresponds to your part's creator signature.
  46. You will also want to add unique icons for your part so that users can
  47. distinguish between your part and others. Changing these two things is a
  48. matter of manipulating your 'BNDL' resources and setting the appropriate
  49. creator type in your development environment.
  50.  
  51. So the basic checklist of resources to modify is as follows:
  52.  
  53.    - 'nmap' resources
  54.    - Mac OS creator type for the part
  55.    - Mac OS icons for the part
  56.  
  57.  
  58. Modifying Your 'nmap' Resources
  59.  
  60. Your part can have several 'nmap' resources, depending on the types of data
  61. your part supports and the structure of your part editor. The most commonly
  62. used 'nmap' resources are as follows:
  63.  
  64.    - Kind->Category mapping
  65.    - Editor->Kind mapping
  66.    - Editor User String
  67.    - Kind User String
  68.    - Category User String (only if you do not use an OpenDoc defined category)
  69.    - Mac OS Type mapping
  70.  
  71. In addition, you may want to supply one other type of 'nmap' resource to
  72. map platform-types to your part editor, for use during data interchange
  73. operations. This Platform Type mapping is described later in this section.
  74.  
  75. Note: the following examples assume the creation of a sample part called
  76. YourPart, which is being developed from a basic PartMaker template. This
  77. part supports a custom data format and also supports the data format of
  78. another part called SurfPart. This part can also import 'TEXT' and 'PICT'
  79. data from standard Mac OS applications.
  80.  
  81. The OpenDoc Developer Release CDs also have documentation that describes
  82. how to create 'nmap' resources for your part. See these documents for more
  83. information about 'nmap' resources.
  84.  
  85. Kind->Category mapping
  86. The Kind->Category mapping allows OpenDoc to map the data format(s) defined
  87. by your part to a more generic category, such as Text or Graphics. The
  88. basic format of this resource looks like the following:
  89.  
  90. resource kODNameMappings (kKindCategoryMapId)
  91. {
  92.     kODKind,
  93.     {
  94.         kYourPartKind,
  95.         kODIsAnISOStringList
  96.         {
  97.             {
  98.                 kODCategoryDrawing,
  99.                 kYourNewCategory
  100.             }
  101.         }
  102.     }
  103. }
  104.  
  105. In this example, the kYourPartKind string is an ISO string describing the
  106. data format supported by your part. The constant kODCategoryDrawing is
  107. defined by OpenDoc as the generic category for object-oriented graphics
  108. formats. The kYourNewCategory is a custom category that also describes the
  109. part's data. You do not have to support multiple categories in your part,
  110. only the ones that make sense for your data.
  111.  
  112. You must change the text of the kYourPartKind string to match the data
  113. format your part supports. You must also change category string(s) to match
  114. the category(s) that your part's data falls into.
  115.  
  116. Editor->Kind mapping
  117. The Editor->Kind mapping allows OpenDoc to map your part editor to the data
  118. format(s) it supports in its storage unit. The basic format of this
  119. resource looks like the following:
  120.  
  121. resource kODNameMappings (kEditorKindMapId)
  122. {
  123.     kODEditorKinds,
  124.     {
  125.         kYourPartEditor,
  126.         kODIsAnISOStringList
  127.         {
  128.             {
  129.                 kYourPartKind,
  130.                 kSurfPartKind
  131.             }
  132.         }
  133.     }
  134. }
  135.  
  136. In this example, you would need to change the kYourPartKind string to match
  137. your part's data format. Do not change the kYourPartEditor string since
  138. PartMaker sets this information correctly when you generate the part.
  139.  
  140. If your part supports multiple data formats, make sure that you list the
  141. formats in order of fidelity, starting with your part's native format.
  142.  
  143. Editor User String
  144. The Editor User String resource allows OpenDoc to map an instance of your
  145. part to a user-readable text string.
  146.  
  147. resource kODNameMappings (kEditorUserStringMapId)
  148. {
  149.     kODEditorUserString,
  150.     {
  151.         kYourPartEditor,
  152.         kODIsINTLText
  153.         {
  154.             smRoman,
  155.             langEnglish,
  156.             kEditorUserString
  157.         }
  158.     }
  159. }
  160.  
  161. In this example, you would need to change the text of the kEditorUserString
  162. to identify your part. This text could contain something like "My Part
  163. 1.0".
  164.  
  165. Kind User String
  166. The Kind User String resource allows OpenDoc to map the kinds of data
  167. supported by your part to user-readable strings.
  168.  
  169. resource kODNameMappings (kEditorUserStringMapId)
  170. {
  171.     kODKindUserString,
  172.     {
  173.         kYourPartKind,
  174.         kODIsINTLText
  175.         {
  176.             smRoman,
  177.             langEnglish,
  178.             kYourKindUserString
  179.         }
  180.     }
  181. }
  182.  
  183. In this example, you would need to change the text of the
  184. kYourKindUserString to identify your data. This text would contain
  185. something like "My Part data". If you hadn't changed the kYourPartKind
  186. string already, you would also need to do that.
  187.  
  188. Category User String
  189. The Category User String resource allows OpenDoc to map the categories
  190. supported by your part to user-readable strings. You do not have to specify
  191. this resource if your part uses only OpenDoc standard categories.
  192.  
  193. resource kODNameMappings (kEditorUserStringMapId)
  194. {
  195.     kODKindUserString,
  196.     {
  197.         kYourNewCategory,
  198.         kODIsINTLText
  199.         {
  200.             smRoman,
  201.             langEnglish,
  202.             kYourCategoryUserString
  203.         }
  204.     }
  205. }
  206.  
  207. In this example, you would need to change the text of the kYourNewCategory
  208. and kYourCategoryUserString since they are specific to your part. You do
  209. not need to specify a text string for the kODCategoryDrawing category,
  210. since OpenDoc defines this string already.
  211.  
  212. Mac OS Type mapping
  213. The Mac OS Type mapping allows OpenDoc to map the data formats supported by
  214. your part to Mac OS types. The basic format of this resource looks like the
  215. following:
  216.  
  217. resource kODNameMappings (kEditorKindMapId)
  218. {
  219.     kODKindOldMacOSType,
  220.     {
  221.         kYourPartKind,
  222.         kODIsMacOSType
  223.         {
  224.             kYourPartMacOSType
  225.         },
  226.  
  227.         kSurfPartKind,
  228.         kODIsMacOSType
  229.         {
  230.             kSurfPartMacOSType
  231.         },
  232.     }
  233. }
  234.  
  235. In this example, you would need to change the kYourPartMacOSType to match
  236. your part's Mac OS type. If you hadn't changed the kYourPartKind string
  237. already, you would also need to do that.
  238.  
  239.  
  240. Platform Type mapping
  241. In addition to OpenDoc part types, your part can support types such as
  242. 'TEXT' and 'PICT', used by existing applications. To do this, you must
  243. create a new 'nmap' resource of the type kODEditorPlatformKind. In this
  244. resource, specify the OSType's that your part supports. (You must also
  245. specify a user string and category for these types in your resource.) The
  246. following example shows how you would support both 'TEXT' and 'PICT'
  247. resources.
  248.  
  249. resource kODNameMappings (kEditorPlatformKinds)
  250. {
  251.     kODEditorPlatformKind,
  252.     {
  253.         kYourPartEditor,
  254.         kODIsPltfmTypeSpac
  255.         {
  256.             {
  257.                 /* First type */
  258.                 kODPlatformFileType,
  259.                 kTEXTOSType,
  260.                 smRoman,
  261.                 langEnglish,
  262.                 kDragKindUserString1,
  263.                 kODCategoryPlainText,
  264.  
  265.                 /* Second type */
  266.                 kODPlatformFileType,
  267.                 kPICTOSType,
  268.                 smRoman,
  269.                 langEnglish,
  270.                 kDragKindUserString2,
  271.                 kODCategoryDrawing
  272.             }
  273.         }
  274.     }
  275. }
  276.  
  277.  
  278. Changing Your Part Signature
  279.  
  280. You must define a unique signature that distinguishes your part from other
  281. parts. This signature is a four-byte code and is analagous to an
  282. application creator type. You specify this signature in your part's 'BNDL'
  283. resource and to your development environment when you are building your
  284. part. See the documentation that comes with your development environment
  285. for setting this signature.
  286.  
  287.  
  288. Changing Your Part Icons
  289.  
  290. There are two places where you need to identify your part's icons: your
  291. 'BNDL' resource and your Part Info resource. You can modify your 'BNDL'
  292. resource in the same way you would for an application. Your Part Info
  293. resource is an ODF custom resource that identifies the icon family that
  294. OpenDoc uses to display your part as either a large or small icon within a
  295. document.
  296.  
  297. The Part Info resource contains three pieces of information and looks like
  298. the following:
  299.  
  300. resource FW_RPartInfo(kPartInfoID)
  301. {
  302.         // ----- Icon ID
  303.         kViewAsIconID,
  304.  
  305.         // ----- Part Name
  306.         kEditorUserString,
  307.  
  308.         // ----- PartKind
  309.         kYourPartKind
  310. };
  311.  
  312. See the document "PartInfo Resource" for more information.
  313.  
  314. ---------------------------------------------------------------------
  315.  
  316. OpenDoc
  317. Development
  318. Framework
  319.  
  320.  
  321. Part Info Resource
  322. ODF Release 1
  323.  
  324.  
  325.  
  326. ODF 1 introduces a "Part Info" resource that must be defined by all ODF
  327. parts. This resource contains information that were, in previous releases,
  328. passed to the FW_CPart constructor.
  329.  
  330. The Part Info resource looks like this (taken from ODFTable, PartInfo.fr):
  331.  
  332. //--------------------------------------
  333. //      PartInfo Resource
  334. //--------------------------------------
  335.  
  336. resource FW_RPartInfo(kPartInfoID)
  337. {
  338.         // ----- Icon ID
  339.         kViewAsIconID,
  340.  
  341.         // ----- Part Name
  342.         kEditorUserString,
  343.  
  344.         // ----- PartKind
  345.         kKind
  346. };
  347.  
  348. The first field is the default icon ID used when a frame is viewed as an
  349. icon. You will usually reference the document icon defined in your BNDL
  350. resource. If you want to choose or create the icon dynamically, you can
  351. override FW_CFrame::GetIcon and provide a different icon.
  352.  
  353. The second field is the Editor User String. This is one of the strings,
  354. usually defined in your Binding.k file, used by your NMAP resources.
  355.  
  356. The last field is your part kind. This is also a string usually defined in
  357. your Binding.k file and used by your NMAP resources.
  358.  
  359. This resource MUST BE present. You will get an assertion if the resource is
  360. missing.
  361.  
  362. The reasons for this resource are:
  363.  
  364.                                 - OpenDoc for Windows doesn't have NMAPs
  365. resources. It is not possible to find the Editor User String and Part Kind
  366. by looking at the NMAP resources
  367.  
  368.                                 - Passing the Editor User String to the
  369. FW_CPart constructor was making localization impossible
  370.  
  371.                                 - Future releases of ODF may add more
  372. fields to this resource so more default behaviors can be built into ODF.
  373. Good candidates are: the menu bar resource ID so ODF could automatically
  374. load your menu bar from resource, the About resource ID so you won't have
  375. to override your FW_CPart::DoMenu method just to present a standard About
  376. box.
  377.  
  378.  
  379.  
  380. --
  381. Mark Lanett, ODF
  382.  
  383.  
  384.